6.4 Composite Sexp Widgets

The syntax for the composite widget construct is:

type ::= (construct [keyword argument]...  component...)

where each component must be a widget type. Each component widget will be displayed in the buffer, and will be editable by the user.

Widget: cons

The value of a cons widget must be a cons-cell whose CAR and CDR have two specified types. It uses this syntax:

type ::= (cons [keyword argument]...  car-type cdr-type)

Widget: choice

The value matched by a choice widget must have one of a fixed set of types. The widget’s syntax is as follows:

type ::= (choice [keyword argument]...  type ... )

The value of a choice widget can be anything that matches any of the types.

Widget: list

The value of a list widget must be a list whose element types match the specified component types:

type ::= (list [keyword argument]...  component-type...)

Thus, (list string number) matches lists of two elements, the first being a string and the second being a number.

Widget: vector

The vector widget is like the list widget but matches vectors instead of lists. Thus, (vector string number) matches vectors of two elements, the first being a string and the second being a number.

The above suffice for specifying fixed size lists and vectors. To get variable length lists and vectors, you can use a choice, set, or repeat widget together with the :inline keyword. If any component of a composite widget has the :inline keyword set, its value must be a list which will then be spliced into the composite. For example, to specify a list whose first element must be a file name, and whose remaining elements should either be the symbol t or two strings (file names), you can use the following widget specification:

(list file
      (choice (const t)
              (list :inline t
                    :value ("foo" "bar")
                    string string)))

The value of a widget of this type will either have the form (file t) or (file string string).

This concept of :inline may be hard to understand. It was certainly hard to implement, so instead of confusing you more by trying to explain it here, I’ll just suggest you meditate over it for a while.

Widget: set

Specifies a type whose values are the lists whose elements all belong to a given set. The order of elements of the list is not significant. Here’s the syntax:

type ::= (set [keyword argument]...  permitted-element ... )

Use const to specify each permitted element, like this: (set (const a) (const b)).

Widget: repeat

Specifies a list of any number of elements that fit a certain type.

type ::= (repeat [keyword argument]...  type)